home *** CD-ROM | disk | FTP | other *** search
/ The 640 MEG Shareware Studio 2 / The 640 Meg Shareware Studio CD-ROM Volume II (Data Express)(1993).ISO / prog / load1_1a.zip / LOAD.DOC next >
Text File  |  1992-03-01  |  23KB  |  488 lines
  1.                                 LOAD v1.1a
  2.  
  3.                  An interpreter for enhanced batch language.
  4.  
  5.  
  6.            Copyright 1992 by Jeff Frownfelter, all rights reserved.
  7.  
  8.                            ┌─────────┐
  9.                      ┌─────┴───┐     │              (R)
  10.                    ──│         │o    │──────────────────
  11.                      │   ┌─────┴╨──┐ │  Association of
  12.                      │   │         │─┘  Shareware
  13.                      └───│    o    │    Professionals
  14.                    ──────│    ║    │────────────────────
  15.                          └────╨────┘    MEMBER
  16.  
  17.  
  18.                  This document can be subject to changes, and
  19.                        supersedes any previous version.
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26. REGISTRATION:
  27.    By reading this, you can be certain that you have received my program,
  28.    LOAD, through Shareware.  The Shareware concept implies that software
  29.    is to be passed freely, from one user to another, for the purpose of
  30.    evaluation.  You may share copies of LOAD with anyone, however, you may
  31.    not sell copies of LOAD for more than $6.00 a copy.  If you decide to
  32.    use LOAD in any productive way, YOU MUST REGISTER IT WITH ME, THE AUTHOR.
  33.    Try it before you buy it, and if you like it, pay me for my expended time
  34.    and energy.  Here is how you can register LOAD:
  35.  
  36.    - Those who wish to own their own personal copy of LOAD, pay only $30.00.
  37.      You will receive:
  38.         1) 1 copy of the most current version of LOAD;
  39.         2) 1 month of technical support.
  40.  
  41.    - Businesses or government agencies that wish to use LOAD internally, pay
  42.      only $60.00.  You will receive:
  43.         1) 1 copy of the most current version of LOAD;
  44.         2) 1 month of technical support;
  45.         3) 1 SITE LICENSE.
  46.  
  47.    - Those who wish to associate and distribute LOAD with a product, submit
  48.      your purpose in writing, and pay only $60.00.  You will receive:
  49.         1) 1 copy of the most current version of LOAD;
  50.         2) 1 month of technical support;
  51.         3) 1 SITE LICENSE.
  52.  
  53.    Send your registration fee to:
  54.       Jeff Frownfelter
  55.       7349 Rockleigh Ave #D
  56.       Indianapolis, IN  46214
  57.    
  58. MODIFICATIONS to LOAD.EXE:
  59.    Those of you who require customization to the LOAD interpreter, feel free
  60.    to submit your request.  I have only included what, I thought, was needed.
  61.    There are no whistles and bells.  It would, however, be easy to add a
  62.    command or two.
  63.  
  64. Credits:
  65.    I wanted to take a moment to acknowledge my wife, Marcella.  Part of our
  66.    time together was sacrificed to develop LOAD.
  67.  
  68. Disclaimer:
  69.    Jeff Frownfelter disclaims all warranties, either express or implied,
  70.    including but not limited to implied warranties of merchantability and
  71.    fitness for a particular purpose, with respect to the product.  Should
  72.    the program prove to be defective, the purchaser assumes the risk of
  73.    paying the entire cost of all necessary servicing, repair, or correction
  74.    and any incidental or consequential damages.  In no event will
  75.    Jeff Frownfelter be liable for any damages whatsoever (including without
  76.    limitation damages for loss of business profits, business interruption,
  77.    loss of business information and the like) arising out of the use of or
  78.    inability to use this product even if Jeff Frownfelter has been
  79.    advised of the possibility of such damages.
  80.  
  81.    Use of this software product for any period of time constitutes your
  82.    assumed acceptance of this agreement and subjects you to it's contents.
  83.  
  84. Requirements:
  85.    - IBM 100% compatible.
  86.    - 128k RAM.
  87.    - DOS 2.0 or above in single user mode, or
  88.      DOS 3.0 or above in share mode.
  89.    - Time to read and understand this document.
  90.  
  91. Contents:
  92.    This version of LOAD is distributed with the following files:
  93.       LOAD.DOC  - This document.
  94.       LOAD.INV  - A printable invoice.
  95.       LOAD.EXE  - The interpreter.
  96.       LOAD.SRC  - An install program for LOAD.  Actually written using LOAD's
  97.                   enhanced batch language.  This is a good example of what
  98.                   LOAD can do for you.
  99.  
  100. Purpose:
  101.    One of my main concerns, as a Shareware author, is presenting my software
  102.    in a user-friendly manner.  I try to make my programs as user-proof as
  103.    possible, however, there is a price to pay.  Usually, such programs become
  104.    large.  The menus, help files, and error detection routines fill up one
  105.    distribution disk, easily.  But what about the installation program?  Yes,
  106.    every user-friendly program should include a user-friendly installation
  107.    that helps the user install the program to most hardware combinations.
  108.    Where can it reside?  Hypothetically, the distribution disk only has 15k
  109.    free.  Let us consider the conventional options that follow:
  110.  
  111.       1) A READ.ME file containing installation notes could be placed on the
  112.          disk, however, most users do not read.  They usually spend more time
  113.          looking for something to execute.
  114.  
  115.       2) An INSTALL.BAT file could be created which will install the program
  116.          to a user-specified destination.  How many user-proof INSTALL.BAT
  117.          files have you seen lately?  Many of them require the user to enter
  118.          a destination drive from the DOS command line.  Others use batch
  119.          utilities that make the user think the batch file is capable of
  120.          implementing colorful, interactive, pop-up windows, however, these
  121.          utilities may cost 10k of disk spece.  In my opinion, batch file
  122.          installations are too sloppy or clumsy to be associated with a decent
  123.          piece of software.  Besides, did you know that every command executed
  124.          in a batch file requires the use of COMMAND.COM.
  125.  
  126.       3) An INSTALL.EXE file could be compiled which specifically installs
  127.          the program.  This is what I used to do, however, it was a tedious
  128.          process which involved much debugging.  Also, it meant keeping track
  129.          of, yet, another piece of source code for the purpose of future
  130.          modications.
  131.  
  132.    What is left?  I have often considered creating a generic installation
  133.    program, but such a program would be too big.  Instead, I have developed
  134.    an interpreter for enhanced batch language,  The interpreter is small,
  135.    and the language is designed to be compact.  I call it LOAD (Language
  136.    Oriented Aid for the Distributor).  An easy to write, easy to use,
  137.    installation program, written in LOAD, might take five minutes to produce.
  138.    The total disk space required to hold the LOAD interpreter, plus the
  139.    LOAD source file, probably would not exceed 10k.
  140.  
  141.    LOAD can be used in other ways.  It compliments DOS since it can replace
  142.    its batch language.  Convert all of your batch files to LOAD.
  143.  
  144. Features:
  145.    - A small EXE, less than 7.9k.
  146.    - A fast, powerful, easy to learn, compact, interpreted language.
  147.    - Independant execution of commands, unlike normal DOS batch language
  148.      which returns to the calling batch file each time a command is executed.
  149.    - All commands supported by DOS.
  150.    - Screen handling including optional, automatic, page breaks.
  151.    - Direct and user assigned, string variables.
  152.    - Nested macros.
  153.    - Full, conditional and unconditional branching.
  154.    - Two preset variables, STARTDRV and STARTDIR, which indicate what
  155.      drive and directory LOAD was executed from.
  156.    - A trace command for debugging purposes.
  157.    - A preset source file name, LOAD.SRC, which LOAD automatically looks
  158.      for when executed.  This file name can be over-ridden from the command
  159.      line.
  160.    - An optional share flag for LANs.
  161.  
  162. General rules:
  163.    - All source files must have a .SRC extention.
  164.    - At the command line, you may override the default source file name with
  165.      another file name, however, if you accept the default, LOAD.SRC, it must
  166.      be in the directory LOAD was executed from.
  167.    - For DOS commands, LOAD reads your COMSPEC.  If COMSPEC is set to nothing,
  168.      and your source code executes a DOS command, you must either set your
  169.      COMSPEC, or pass a COMSPEC value to LOAD from the command line.  Note that
  170.      your COMSPEC can only be null if you specifically set it to nothing from
  171.      the command line.
  172.    - A source file's size can never exceed 65,535 bytes, however, source files
  173.      can be called from other source files.
  174.    - The first character on a line of source code must be a command.  Anything
  175.      that follows can be any combination of literals and/or macros.
  176.    - Don't place extra spaces between commands and their expressions. The
  177.      interpreter does not appreciate these kinds of cosmetics in the source.
  178.      It considers every letter, number, or space to be a part of a variable
  179.      name, literal, etc.
  180.    - Character 0, or nil, is used as a flag by the LOAD interpreter.  Do not
  181.      use this character in your source code.  It will confuse the interpreter.
  182.  
  183. Commands:
  184.    * - The COMMENT flag is used when you want to place remarks in your source
  185.        code.  Documented source is usually easier to follow.  Comment lines
  186.        are not loaded by the interpreter, leaving more room, in memory, for
  187.        actual source code.  Use comment lines, freely.
  188.  
  189.        Here are some example comments:
  190.  
  191.           *************************************************************
  192.           * Use an asterisk to place comments, like this one, in your *
  193.           * source code.                                              *
  194.           *************************************************************
  195.  
  196.    A - The ASSIGN command is used to set values to variables.  Follow these
  197.        rules regarding variables:
  198.  
  199.           - A variable names's size can be no larger than 10 characters.
  200.           - These characters (=`~-) may not be used in a variable name.
  201.           - A variable name is considered in a non-case-sensitive manner
  202.             by the interpreter.  Lower case variable names are seen as
  203.             upper-case.
  204.           - A variable value's size can bo no larger than 255 characters.
  205.           - A variable value can only be expanded when the variable name
  206.             is surrounded by the character, "`".  Note that the "`" character
  207.             is on the same key as the tilde (~).
  208.  
  209.        The variable name being assigned should immediately follow the command.
  210.        Immediately following the name of the variable, an equal sign (=) should
  211.        appear.  This character tells the interpreter where the variable name
  212.        ends and the value begins.
  213.  
  214.        The tilde (~) carries a special meaning in an assignment.  When a
  215.        variable name is surrounded by a tilde, the variable name is not
  216.        expanded to its value.  Instead, the tildes are replaced with the
  217.        "`" character, and the variable name is stored in the string being
  218.        assigned.  Once again, this only occurs in an assignment.  This is
  219.        useful when you need to create a nested macro where a variable's value
  220.        can contain another variable's name.  The interpreter always expands
  221.        macros recursively.
  222.  
  223.        Here are some example assignments:
  224.  
  225.           aFirstName=Jeff
  226.           aLastName=Frownfelter
  227.           ****************************************************
  228.           * The value of Name will equal "Jeff Frownfelter". *
  229.           ****************************************************
  230.           aName=`FirstName` `LastName`
  231.  
  232.           aCommand=DIR
  233.           aParameter=/P
  234.           ********************************************************************
  235.           * The value of CmdLine will equal "~Command~~Parameter~".  These   *
  236.           * two varialbes will be expanded when CmdLine is expanded.  This   *
  237.           * is how nested macros are implemented, and their uses will become *
  238.           * apparent with experience.                                        *
  239.           ********************************************************************
  240.           aCmdLine=~Command~~Parameter~
  241.           *********************************************************************
  242.           * The value of CmdLine will now equal "DIR /P", because the         *
  243.           * interpreter will completely expand CmdLine's value and the nested *
  244.           * macros inside of it.                                              *
  245.           *********************************************************************
  246.           aCmdLine=`CmdLine`
  247.  
  248.    B - The TOGGLE BREAK command toggles an internal, screen, page break
  249.        varialbe.  By default, anytime the screen fills up with text without
  250.        any kind of pause, an automatic page break will occur with an
  251.        appropriate message to the user.  This default can be toggled OFF,
  252.        and back ON, with this command.
  253.  
  254.        Here is an example:
  255.  
  256.           *************************
  257.           * Toggle page break OFF *
  258.           *************************
  259.           b
  260.  
  261.           ***********************************************************
  262.           * Full screen of text, such as a large menu, can go here. *
  263.           ***********************************************************
  264.  
  265.           ************************
  266.           * Toggle page break ON *
  267.           ************************
  268.           b
  269.  
  270.    C - The CONDITIONAL command is used to conditionally remove unwanted
  271.        characters from the end of a variable's value.  Such a command is
  272.        useful when validating a user, specified, drive or path.  Many times,
  273.        you will need make sure that a path variable does not have too many
  274.        colons (:) or backslashes (\).
  275.  
  276.        The variable name being assigned should immediately follow the command.
  277.        Immediately following the name of the variable, a minus sign (-) should
  278.        appear.  This character tells the interpreter where the variable name
  279.        ends and the character to remove begins.
  280.  
  281.        If the last character in the variable's value is equal to the character
  282.        specified, the last character of the variable's value will be removed.
  283.        This will continue until there are no more matching characters.
  284.  
  285.        Here is an example:
  286.  
  287.           aDrive=C:::::
  288.           cDrive-:
  289.           **************************************
  290.           * The value of Drive will equal "C:" *
  291.           **************************************
  292.           aDrive=`Drive`:
  293.  
  294.    E - The ERASE command is used to erase the screen.  If automatic page
  295.        break is ON, the screen line counter is reset to one.
  296.  
  297.        Here is an example:
  298.  
  299.           ************************************************
  300.           * The following command will erase the screen. *
  301.           ************************************************
  302.           e
  303.  
  304.    G - The GOTO command is used to perform conditional and unconditional
  305.        branching to labels.  A label is like a command since it resides
  306.        on a line by itself, or with other labels.  It is unlike a command
  307.        since it is not executed.  Labels only exist for the purpose of
  308.        being branched to by the GOTO command.  As with all LOAD commands,
  309.        GOTO and labels are integrated with LOAD's powerful, macro capabilities.
  310.        Also, both GOTO and labels are considered in a non-case-sensitive
  311.        manner by the interpreter.  Lower case and upper case characters
  312.        are considered the same.
  313.   
  314.        The GOTO command searches, from line one of the source code, to
  315.        the last line for a matching label.  If a matching label is not
  316.        found, execution resumes at the line following the GOTO command.
  317.        This technic provides IF-THEN-ELSE branching.
  318.  
  319.        Note that labels can be 255 characters in length.  I cannot imagine
  320.        pushing a label to that length, but where there is a will...
  321.  
  322.        Here are some example GOTOs with labels:
  323.  
  324.           aDirectory=\DOS
  325.           ******************************************************************
  326.           * The following will assure that the variable Directory has one  *
  327.           * backslash as the last character.  This routine is very common. *
  328.           * The final result of the directory variable will be "\DOS\".    *
  329.           ******************************************************************
  330.           g10`Directory`
  331.           aDirectory=`Directory`\
  332.           g20
  333.           :10\
  334.           aDirectory=\
  335.           :20
  336.  
  337.    I - The INPUT command is used to assign user input to a variable.  This
  338.        command is like the ASSIGN command, with one exception.  Any text
  339.        that follows the equal sign (=) will be written to the screen
  340.        before the user is prompted.  A space will automatically place
  341.        itself between the text and the prompt.  If there is no text
  342.        following the equal sign, an extra space will not be inserted.
  343.  
  344.        Since this command results in a pause to the flow of execution,
  345.        the page break, screen line counter is reset to one.
  346.  
  347.        Here is an example:
  348.  
  349.           :Retry
  350.           aConfirm=Yes
  351.           iConfirm=Are you sure (Yes/No; <ENTER>=`Confirm`)?
  352.           g10`Confirm`
  353.           gRetry
  354.           :10Y:10Yes
  355.           aConfirm=Y
  356.           g20
  357.           :10N:10No
  358.           aConfirm=N
  359.           ***************************************************************
  360.           * At this point, the value of Confirm would equal "Y" or "N", *
  361.           * no matter what!                                             *
  362.           ***************************************************************
  363.           :20
  364.  
  365.    P - The PAUSE command is used when you want to write a message to the
  366.        screen, and pause until the user presses any key.  Basically, this
  367.        command forces the interpreter to perform a page break.  Of course,
  368.        a pause command can be issued without writing anything to the screen.
  369.  
  370.        Here is an example:
  371.  
  372.           *********************************************************************
  373.           * A message, "Ready to return to menu!", will appear on the screen. *
  374.           * An appropriate pause message to the user will follow.             *
  375.           *********************************************************************
  376.           pReady to return to menu!
  377.  
  378.    O - The OS (operating system) command is used to execute DOS commands.
  379.        Any valid DOS command may follow this command.  If nothing follows
  380.        this command, the interpreter will shell to DOS where the EXIT command
  381.        must be issued in order to return to the calling LOAD program.
  382.  
  383.        Here is an example:
  384.  
  385.           *****************************************************************
  386.           * The following command will display the current DOS directory. *
  387.           *****************************************************************
  388.           oDIR /P
  389.  
  390.    T - The TOGGLE TRACE command is used in source debugging.  By default,
  391.        this option is turned OFF.  When this command is executed, the
  392.        interpreter will echo each command that it expands and executes, until
  393.        the trace command is once again executed.  Since comments are not loaded
  394.        at execution time, you will not see them echoed.
  395.  
  396.        Here is an example:
  397.  
  398.           ***********************
  399.           * Turn trace mode on. *
  400.           ***********************
  401.           t
  402.  
  403.           *******************************************************
  404.           * Commands executed here will be echoed to the screen *
  405.           *******************************************************
  406.  
  407.           ************************
  408.           * Turn trace mode off. *
  409.           ************************
  410.           t
  411.  
  412.    W - The WRITE LINE command is used to output information to the screen.
  413.        A carriage-return/line-feed will be issued immediately afterwards.
  414.        Note that this command directly affects automatic page breaks.
  415.        You may also use this command to advance one screen line, however,
  416.        such a command is the same as placing a blank line in the source code.
  417.  
  418.        Here is an example:
  419.  
  420.           *******************************************************************
  421.           * The following commands will output the following to the screen: *
  422.           *    Hello,                                                       *
  423.           *                                                                 *
  424.           *    My name is Jeff!                                             *
  425.           *******************************************************************
  426.           aName=Jeff
  427.           wHello,
  428.  
  429.           wMy name is `Name`!
  430.  
  431.    ; - The WRITE command is used to output information to the screen.
  432.        Unlike the WRITE LINE command, this command will not issue a
  433.        carriage-return/line-fee.  Also, automatic page breaks are completely
  434.        unaffected by this command.
  435.  
  436.        Here is an example:
  437.  
  438.           *******************************************************************
  439.           * The following commands will output the following to the screen: *
  440.           *    Hello...world!                                               *
  441.           *******************************************************************
  442.           ;Hello...
  443.           wworld!
  444.  
  445. Preset variables:
  446.    Two variables are automatically intialized when you execute LOAD.  These
  447.    variables are,
  448.  
  449.       STARTDRV - This variable contains the drive letter that LOAD was
  450.                  executed from.  The value will be upper case, and it
  451.                  will not include a colon (:).
  452.  
  453.       STARTDIR - This variable contains the directory that LOAD was executed
  454.                  from.  The value will be upper case, and it will not include
  455.                  a trailing backslash (\), unless the backslash represents a
  456.                  root directory.
  457.  
  458. CTRL-BREAK:
  459.    This key combination has not been disabled.  The user can break the
  460.    flow of a program at any time.
  461.  
  462. Command line syntax:
  463.   Usage: LOAD [Options]
  464. Options: {file name}.SRC (default=LOAD.SRC)
  465.          {comspec}
  466.          /S (share mode)
  467.          /? (these options)
  468.  
  469. Standard errors:
  470.      Cannot load - The interpreter could not load the source file.  Remember
  471.                    that LOAD.SRC is always the file LOAD looks for if the
  472.                    user does not specify an opposing source file at the DOS
  473.                    command line.  Also, source file names must have a .SRC
  474.                    extention.
  475.    Out of memory - LOAD requires 128k of RAM to operate properly.  LOAD
  476.                    uses any memory you have to create memory variables.
  477.                    If a variable is created when there is no more room in
  478.                    memory to create it, this error will occur.
  479. Cannot shell out - When the O command is issued, if COMSPEC is not set, or
  480.                    memory has been used up, this error will appear.
  481.      Bad command - A command was executed in the source that is not part
  482.                    of the command language.
  483.  
  484. Summary:
  485.    It took much time and experience to create this program.  I hope you value
  486.    its usefulness, just as I have.
  487.  
  488.